No part of this work may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or by any information storage and retrieval system, without permission in writing from the publisher. However, you are permitted to make copies of this work, printed or otherwise, as long as said copies are for your personal use only.
-------
DialogerPro is by far one of the best reasons to own MicroPhone II or MicroPhone Pro. Unfortunately, it is one of the least documented aspects of the product. With it, you can design a graphical interface to just about any electronic service. You can even go as far as developing a pseudo database or address book with it. There are innumerable uses for it, and you can create everything from a mundane profile or alert, to a profound, ever-changing panel of complex controls.
What we will do in this tutorial is guide you step-by-step into designing a simple dialog with two buttons (OK and Cancel), three static text fields, and three edit text fields. If you don't already have ResEdit 2.1 or higher, you'll need it. So, stop now and find it on your local BBS or one of the major online services.
Psychology of Everyday Dialogs
Designing dialogs can be the most time-consuming task of developing a product. If they become cluttered or hard to use, people won't want to touch your product. Fortunately, the dialog we are about to design is simple and straightforward.
Here, you will create a new dialog called Profile. If you don't have ResEdit, or you don't want to create the dialog, a copy of it is available in the DP Tutorial Pt.1 settings document.
Follow these step-by-step instructions to create your new dialog. You'll actually be creating two resources: a DLOG and a DITL. If you get stuck, or you would like to see what the finished dialog should look like, take a look at the DLOG and DITL with the ID 7777 in the DP Tutorial Pt.1 settings document.
Ready for the challenge? Here we go!
1. Open MicroPhone. If you don't already have an untitled settings document up, go to the File menu and choose Close Settings. Then, go to the File menu again and choose New Settings. Once more, go to the File menu and choose Save Settings As…. Name the settings document "DP Test". This is the settings document that will contain your new dialog, as well as the scripts that drive the dialog.
2. Quit MicroPhone and launch ResEdit. ResEdit is the application you will use to create the actual dialog resources. Since you cannot have a document open by two separate applications at the same time, you need to quit MicroPhone before opening "DP Test" with ResEdit.
3. Go to the File menu in ResEdit and choose Open. Find the "DP Test" settings document you created in step 1 and open it.
4. Choose Create New Resource from the Resource menu. Select DLOG from the subsequent dialog. You are going to create a DLOG, which is a set of instructions that tells the system how to draw the dialog, how large the dialog will be, and what the dialog will look like.
5. Choose Get Resource Info from the Resource menu. Renumber the DLOG "7777" and give it the name "Profile". Close the info window. You'll note that whenever you create a new resource in ResEdit, it is given the ID 128. In order to prevent conflicts with other dialogs that might have the same ID, you want to renumber the dialog, giving it a relatively high and unique number.
6. Change the DITL ID for your DLOG to "7777". A DLOG always points to a corresponding DITL. There's no rule that says the DITL must have the same ID, but in order to avoid confusion, you should always use a DITL ID that correspond to its DLOG ID.
7. Choose Open DITL Editor from the Resource menu. A DITL is a list of items in a dialog. Items can be anything from text fields to list boxes to buttons. Our dialog will have eight items: three static text fields, three edit text fields, and two buttons.
8. Drag a button from the floating palette of available dialog items and place it in the lower right-hand corner of your dialog. If you are unfamiliar with the concept of dragging, it is very similar to dragging files or folders around while you are in the Finder. Simply click on the object you want to drag, and while holding the mouse button down, move the mouse until you reach your destination. Let go of the mouse button and your object (or a copy of your object) should appear at its new destination.
9. Double-click on this new button. An "Edit DITL item" window will appear, allowing you to name, position, and size your object. The four numbers in the Edit DITL item window correspond to the location and size of the button. For now, the default size is fine. Give your button the name "OK", and close the Edit DITL item window. The OK button is item number 1 in your dialog. Item numbers will become important later, when you begin to access the dialog and need to have some way of addressing specific dialog items.
10. Drag another button from the floating palette and place it to the left of the "OK" button. Make sure you leave at least 10 pixels of space between the two buttons. If the buttons do not properly align, or if you want to move them precisely, you can use the cursor keys on your keyboard.
11. Double-click on this button to bring up its Edit DITL item window and give it the name "Cancel". Close the Edit DITL item window.
12. Drag an Edit Text item from the floating palette and place it at the top of the dialog, with about an inch and a half of room on the right and a few pixels of room at the top.
13. Size the Edit Text item and make it about two inches wide. You need to make it wide enough to fit a name or user identification. There should be enough room for a name like "Rumpelstiltskin Jones".
14. Copy the Edit Text item and place the copy below the original. You can copy items simply by selecting them and choosing Copy from the Edit menu. Then, choose Paste from the Edit menu and move the new item to its new location.
15. Copy the Edit text item again and place this copy below the other two. Now, you have three edit fields, enough for a user name, password, and a telephone number of a service to dial.
16. Drag a Static Text item from the palette and place it to the left of the top-most Edit Text item. This is the label for your first Edit Text item.
17. Double-click on the Static Text item, give it the label "Name", and close the Edit DITL item window. If your label is too close to or overlaps the Edit Text item next to it, take this opportunity to move items around a bit, until the dialog items align correctly.
18. Copy the Static Text item and place the copy to the right of the second Edit Text item.
19. Double-click on this Static Text item, give it the label "Password", and close the Edit DITL item window.
20. Copy this Static Text item and place the copy to the right of the third Edit Text item.
21. Double-click on this final Static Text item, give it the label "Phone", and close the Edit DITL item window. You now have labels for your three edit fields.
22. You're done creating the dialog. If you want to line up pixels and make things look a little better, now is your chance. When you are done, close the DITL window and the DLOG window and choose Save from the File menu.
23. Quit ResEdit and open the "DP Test" settings document with MicroPhone. You are going to create a script that will manipulate your new Profile dialog.
24. Go to the Scripts menu and choose Edit Scripts. Create a script called "Profile Test":
1 Set Variable * d0 from Expression "'Profile'"
2 Set Variable * dResult from Expression "MPDialogerPro(d0)"
3 If Expression "ItemFetch(dResult,'^M',1) = 'OK'"
4 Alert * OK "'You clicked the OK button'"
5 Send Local to Screen "'The Name entered was: ' & ItemFetch(dResult,'^M',3) & '^M^J'"
6 Send Local to Screen "'The Password entered was: ' & ItemFetch(dResult,'^M',4) & '^M^J'"
7 Send Local to Screen "'The Phone entered was: ' & ItemFetch(dResult,'^M',5) & '^M^J'"
8 Else If Expression "ItemFetch(dResult,'^M',2) = 'Cancel'"
9 Alert * OK "'You clicked the Cancel button'"
10 End If
This script displays your newly created dialog and tells you if you've hit the OK or Cancel button. Also, if you hit the OK button, it will display in the terminal window the contents of the three Edit Text fields.
Annotation
Line 1 - the name of your dialog is Profile. This is the name you gave it when you created it with ResEdit. You will use this name to refer to the dialog.
Line 2 - MPDialogerPro is the name of an XFCN in MicroPhone that displays dialogs and allows you to manipulate them. In order to use MPDialogerPro, you need to pass to it a set of parameters. Minimally, you need to pass the name of the dialog, which is all that is done for the simple Profile dialog.
Line 3 - Once the OK or Cancel button are clicked, the dialog is dismissed, and the contents of the dialog are stored in the variable dResult, referred to in line 2. You can use any variable you like. For this example, we use an arbitrary variable called dResult. The entire contents of the dialog are placed in this variable, carriage return delimited. So, the contents of the OK button are contained in line 1, the Cancel button in line 2, the first edit field in line 3, etc. By checking line 1 of dResult, you can determine if the OK button was hit. If it was hit, the name of the button appears in this line. Otherwise, the line is blank.
Line 4 - If the OK button had been clicked, an alert is displayed stating this fact. You could do a variety of other things at this point, such as storing off the values in a text file, or setting variables, etc.
Lines 5-7 - The remainder of dResult is displayed in the terminal window. You could just as well use the values to log onto a real host somewhere.
Lines 8-9 - If line 2 of dResult contains the word "Cancel", you know that the Cancel button was hit. Because you don't usually want to do anything if the Cancel button in a dialog is hit, nothing further really happens in the script. However, for testing purposes, to show you that this aspect of the dialog really works, an alert is displayed.
Line 10 - Ends the If condition that began on line 3.
OTHER EXAMPLES
In the DP Tutorial Pt.1 settings document, you'll see several examples of how to interact with this dialog. Click on the "Scripts" button to display the following examples:
"Profile" calls another script called "Profile_read" which reads the contents of a text file called PROFILE.TXT. It then displays the contents in a dialog similar to the one you just created. If you click the OK button, it calls a script called "Profile_write" that writes the new information to the PROFILE.TXT file.
"Profile2" is similar to "Profile" except it protects the profile field, so you cannot see the password when you type it in.
"Profile3" changes the font of the Edit Text fields to Geneva 12, instead of the default Chicago 12.
"Profile4" asks for confirmation before overwriting your original profile information.
NEXT TIME
We'll take the Profile dialog one step further by introducing a "hit handler". Hit handlers allow you to interact directly with the dialog. You can do things like check all the edit text fields for a value before dismissing the dialog. We will also make some additions to our Profile dialog, including a popup menu.
